<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>query_script_throttle: common_schema documentation</title>
	<meta name="description" content="query_script_throttle: common_schema" />
	<meta name="keywords" content="query_script_throttle: common_schema" />
	<link rel="stylesheet" type="text/css" href="css/style.css" />
</head>

<body>
	<div id="main">
		<div id="header">
			<h1>common_schema</h1> <strong>2.2</strong> documentation
			<div class="subtitle">DBA's framework for MySQL</div>
		</div>
		<div id="contentwrapper">
			<div id="content">
				<h2><a href="query_script_throttle.html">query_script_throttle</a></h2>	

<p>
<strong>throttle</strong>: regulate execution of script by sleep-suspend
</p>

<h3>SYNOPSIS</h3>
<p>
<blockquote><pre>
while (expression)
{
  statement;
  throttle &lt;number&gt;;
}
</pre></blockquote>
<blockquote><pre>
while (expression)
{
  statement;
  throttle $throttle_ratio;
}
</pre></blockquote>
</p>

<h3>DESCRIPTION</h3>
<p> 
<i>throttle</i> is a QueryScript <a href="query_script_statements.html">statement</a> which,
when invoked, may suspend execution by invoking 
<a href="http://dev.mysql.com/doc/refman/5.1/en/miscellaneous-functions.html#function_sleep">SLEEP()</a>.
</p>
<i>throttle</i> takes a number as a parameter, which is the ratio of throttling. The number can be an integer
or a floating point, and it is interpreted as follows:
<ul>
	<li><strong>0 or less</strong>: no throttling is done. It makes no sense to provide such values</li>
	<li><strong>x, a positive number</strong>: assuming an unthrottled operation would take <strong>s</strong> seconds to run,
		a throttled operation is expected to run <strong>s*(1 + x)</strong> seconds.</li>
</ul>
</p>
<i>throttle</i> also accepts a local variable or a MySQL user defined variable as argument. 
Such argument is cast to a number and handled as specified above. 
</p>

<p>
Consider the following code as example:
<blockquote><pre>
while (delete from world.City limit 10)
{
  throttle 1;
}
</pre></blockquote>
The above deletes all rows from a table, 10 rows at a time. The throttle value of <strong>1</strong> means doubling the runtime:
if the original deletion loop would take <strong>7</strong> seconds to complete, the <i>throttle</i> statements adds one measure to that, resulting
with <strong>14</strong> seconds.
</p>

<p>
A <i>throttle</i> value of <strong>2</strong> would make the code run <strong>3</strong> times as long it it would without throttling.
A <i>throttle</i> value of <strong>0.3</strong> would make the code run <strong>1.3</strong> times as long it it would without throttling.
</p>

<p>
Combined with loop iteration, throttling makes for heavy duty query put less load on the system. That is, CPU or disk resources, which
may be extensively used during normal query or queries iteration, are given breathing space during throttle suspension period.
Throttling makes for a longer total runtime, while making pauses in between operations. Throttling is also a useful technique in avoiding
replication lag: standard MySQL replication (5.1, 5.5) is single threaded. Throttling allows the slave to execute other queries, interleaved
with script statements.  
</p>
<p>
While this statement is valid anywhere throughout the script, it mostly makes sense when executed from within a loop, such that
the iterations of the loop are being throttled.</p>
<p>

<h3>EXAMPLES</h3>

<p>
Duplicate a table: copy rows in small chunks, throttle:
<blockquote><pre>
create table world.City2 like world.City;
split (insert into world.City2 select * from world.City)
{
  throttle 2;
}
</pre></blockquote>
</p>

<h3>SEE ALSO</h3>
<a href="query_script_execution.html">Execution</a>,
<a href="query_script_flow_control.html">Flow control</a>,
<a href="query_script_sleep.html">sleep</a>

<h3>AUTHOR</h3>
Shlomi Noach


				<br/>
			</div>
			<div id="sidebarwrapper">
				<div id="search">
					Search online documentation
					<form id="search_form" name="search_form" method="GET" 
						action="http://www.google.com/search" 
						onsubmit="document.forms['search_form']['q'].value = 'site:http://common-schema.googlecode.com/svn/trunk/common_schema/doc/html/ '+document.forms['search_form']['search_term'].value;">
						<input type="text" name="search_term" value=""/>
						<input type="hidden" name="q" value=""/>
						<input type="submit" value="go"/>						
					</form>
				</div>
				<div id="menu">
					<ul>
						<li><a title="Introduction" href="introduction.html">Introduction</a></li>
						<li><a title="Documentation" href="documentation.html">Documentation</a></li>
						<li><a title="Download" href="download.html">Download</a></li>
						<li><a title="Install" href="install.html">Install</a></li>
						<li><a title="Risks" href="risks.html">Risks</a></li>
					</ul>						
					<h3>QUERY SCRIPT</h3>
					<ul>
						<li><a title="QueryScript" href="query_script.html">QueryScript</a></li>
						<li><a title="Execution" href="query_script_execution.html">Execution</a></li>
						<li><a title="Flow control" href="query_script_flow_control.html">Flow control</a></li>
						<li><a title="Statements" href="query_script_statements.html">Statements</a></li>
						<li><a title="Expressions" href="query_script_expressions.html">Expressions</a></li>
						<li><a title="Variables" href="query_script_variables.html">Variables</a></li>
					</ul>						
					<h3>DEBUG</h3>
					<ul>
						<li><a title="rdebug" href="rdebug.html">rdebug</a></li>
						<li><a title="rdebug API" href="rdebug_api.html">rdebug API</a></li>
						<li><a title="rdebug workflow" href="rdebug_workflow.html">Workflow</a></li>
					</ul>						
					<h3>ROUTINES</h3>
					<ul>
						<li><a title="Execution &amp; flow control" href="execution_routines.html">Execution & flow control</a></li>
						<li><a title="General" href="general_routines.html">General</a></li>
						<li><a title="Process" href="process_routines.html">Process</a></li>
						<li><a title="Query analysis" href="query_analysis_routines.html">Query analysis</a></li>
						<li><a title="Schema analysis" href="schema_analysis_routines.html">Schema analysis</a></li>
						<li><a title="Security" href="security_routines.html">Security</a></li>
						<li><a title="Text" href="text_routines.html">Text</a></li>
						<li><a title="Time &amp; date" href="temporal_routines.html">Time & date</a></li>
						<li><a title="Charting" href="charting_routines.html">Charting</a></li>
					</ul>
					<h3>VIEWS</h3>
					<ul>
						<li><a title="Schema analysis" href="schema_analysis_views.html">Schema analysis</a></li>
						<li><a title="Data dimension" href="data_dimension_views.html">Data dimension</a></li>
						<li><a title="Process" href="process_views.html">Process</a></li>
						<li><a title="Security" href="security_views.html">Security</a></li>
						<li><a title="Monitoring" href="monitoring_views.html">Monitoring</a></li>
						<li><a title="InnoDB Plugin" href="innodb_plugin_views.html">InnoDB Plugin</a></li>
						<li><a title="Percona server" href="percona_server_views.html">Percona Server</a></li>
						<li><a title="TokuDB" href="tokudb_views.html">TokuDB</a></li>
					</ul>						
					<h3>DATA</h3>
					<ul>
						<li><a title="tables" href="tables.html">Tables</a></li>
						<li><a title="variables" href="variables.html">Variables</a></li>
					</ul>						
					<h3>META</h3>
					<ul>
						<li><a title="Help" href="help.html">help</a></li>
						<li><a title="Metadata" href="metadata.html">metadata</a></li>
						<li><a title="status" href="status.html">status</a></li>
					</ul>						
				</div>
			</div>	
			<div class="clear">&nbsp;</div>
			
			<div id="footnote" align="center">
				<a href="">common_schema</a> documentation
			</div>
		</div>
	</div>
</body>
</html>
